The Break Loop

The break loop is a read-eval-print loop similar to the top-level loop. In addition to ordinary Lisp forms, the break loop accepts various commands with which the user can inspect and modify the state of the program execution. Each break loop command is identified with a keyword (i.e., a symbol in the keyword package). A break loop command is executed when the user inputs a list whose first element is the keyword that identifies the command. The rest of the list is the arguments to the command. They are evaluated before being passed to the command. If the command needs no arguments, then the user may input only the keyword. It is an error if the given keyword does not identify any command. Any other input to the break loop is regarded as an ordinary Lisp form; the form will be evaluated and the resulting values will be printed on the terminal.

There can be several instances of the break loop at the same time, and each such instance is identified by a level number. When the break loop is entered during execution in the top-level loop, the break loop instance is given the level number 1 . The break loop instance that is entered from the level n break loop is given the level number n + 1 . The prompt of the level n break loop is n + 1 consecutive >'s, occasionally prefixed with the name of the current package.

The break loop keeps track of the invocation sequence of functions (including special forms and macro expansion functions), which led up to the break loop from the previous break loop (or from the top-level loop, if the current break loop is level 1 ). The invocation sequence is maintained in a pushdown stack of events. An event consists of an event function and an event environment. An event function is:

1. an interpreted (i.e., not compiled) function (global function, local function, lambda-expression, or closure),
2. a special form within an interpreted function,
3. a macro expansion function called from an interpreted function,
4. a compiled function called from an interpreted function, or
5. a compiled function called from another compiled function which was compiled while the safety optimize level is 3 or with a notinline declaration for the called function (see Chapter 7).

An event is pushed on the event stack when execution of its event function begins, and is poped away at the completion of the execution. An event environment is the `environment' of the event function at the time the next event is pushed. Actually, an event environment is a pointer to the main stack of KCL. For each interpreted event function (i.e., event function in classes 1, 2, and 3), the pointer points to the first entry of the three contiguous main stack entries that hold the lexical environment of the event function. For each compiled event function (i.e., event function in classes 4 and 5), the pointer is set to the first entry of the main stack area that is used locally by the compiled code. In most cases, the first argument to the compiled function is saved in the first entry, the second argument in the second entry, and so on. The local variables of the function are allocated in the entries following the arguments. However, this is not always the case. Refer to Section 7.3 for variable allocations in compiled functions.

By break level commands, the user can choose one of the events as the current event. If the current event function is an interpreted event function, then the break loop evaluates Lisp forms in the lexical environment retrieved from the event environment. In particular, local variables may be referenced by the variable names, local functions and local macros may be invoked as usual, established blocks may be exited from, and tags may be used as the destination of go. If the current function is a compiled function, Lisp forms are evaluated in the null environment.

Within the break loop, each event is represented by the event symbol. The :backtrace command, for example, lists events in terms of their event symbols. If the event function is a named function (global or local) or a macro expansion function, then the function or macro name is used as the event symbol. If the event function is a special form, then the name of the special form is used. If the event function is a lambda-expression (or a closure), then the symbol lambda (or lambda-closure ) is used.

To suppress unnecessary information, the user can hide (or make invisible) some of the events. Invisible events do not appear in the backtrace, for example. Initially, only those events are invisible whose event symbols belong to the system internal package system. When the break loop is entered, the last visible event becomes the current event.

The break loop commands are described below. Some of the commands allow abbreviation in the keywords that identify them. For example, the user may abbreviate :current as :c. The break loop commands return no values at all.

:current[Break Loop Command]
:c[Abbreviated Break Loop Command]

Prints the event symbol of the current event.

:previous &optional n[Break Loop Command]
:p &optional n[Abbreviated Break Loop Command]

Makes the n-th previous visible event the new current event. Invisible events are not counted. If there are less than n previous events, then the first visible event in the invocation sequence becomes the new current event. n must be a positive integer and the default is 1.

:next &optional n[Break Loop Command]
:n &optional n[Abbreviated Break Loop Command]

Makes the n-th next visible event the new current event. If there are less than n next events, then the last visible event in the invocation sequence becomes the new current event. n must be a positive integer and the default is 1.

:backtrace[Break Loop Command]
:b[Abbreviated Break Loop Command]

Prints the event symbols of all visible events in order. The symbol of the current event is printed in upper-case letters and the event symbols of other events are in lower-case.

:help[Break Loop Command]
:h[Abbreviated Break Loop Command]

Lists the break loop commands.

:quit &optional n[Break Loop Command]
:q &optional n[Abbreviated Break Loop Command]

Returns control to the level n break loop. If n is 0 or if n is omitted, then control will return to the top-level loop. n must be a non-negative integer smaller than the current break level.

:resume[Break Loop Command]
:r[Abbreviated Break Loop Command]

Returns control to the caller of the break loop. If the break loop has been entered from cerror, cerror returns nil as its value and control will resume at that point. Otherwise, this command returns control to the previous break loop (or to the top-level loop, if the current break level is 1).

:variables[Break Loop Command]
:v[Abbreviated Break Loop Command]

Prints the names of the bound variables in the current environment. To see the value of a bound variable, just type the variable name.

:functions[Break Loop Command]

Prints the names of the local functions and local macros in the current environment. To see the definition of a local function or macro, use the function special form in the usual way. That is, (function name) will return the definition of the local function or macro whose name is name. Local functions and local macros may be invoked as usual.

:blocks[Break Loop Command]

Prints the names of the blocks established in the current environment. If a block block is established, then the return-from form (return-from block value ) works as usual. That is, the block form that established block will return value as its value and control will resume at that point.

:tags[Break Loop Command]

Prints the tags established in the current environment. If a tag tag is established, then the go form (go tag) works as usual. That is, control will resume at the position of tag in the surrounding tagbody.

:local &optional n[Break Loop Command]
:l &optional n[Abbreviated Break Loop Command]

If n is 0 or if it is omitted, then this command prints the value stored in the main stack entry that is pointed to by the current event environment. n is an offset from that entry. If n is positive, then the value of the n-th next (i.e., toward the top of the main stack) entry is printed. If n is negative, then the value of the | n |-th previous (i.e., toward the bottom of the main stack) entry is printed. n must be an integer. It is an error if the specified entry does not lie between the bottom and the top of the stack.

:hide symbol[Break Loop Command]

Hides all events whose event symbol is symbol. In particular, by (:hide 'lambda) and (:hide 'lambda-closure) , all events become invisible whose event functions are lambda-expressions and closures, respectively. If the event symbol of the current event happens to be symbol, then the last previous visible event will become the new current event. symbol must be a symbol.

Events of eval and evalhook may never become invisible and attempts to hide them are simply ignored. It is always the case that the first event function is either eval or evalhook. Keeping both of them visible is the simplest way to avoid the silly attempts of the user to hide all events.

:hide-package package[Break Loop Command]

Hides all events whose event symbol belongs to the package package. package may be any object that represents a package, i.e., a package object, a symbol, or a string. If the event symbol of the current event happens to belong to the package package, then the last previous visible event will become the new current event. Even if lisp package was specified as package, events of eval and evalhook do not become invisible. See the description of :hide above.

:unhide symbol[Break Loop Command]

:unhide is the inverse command of :hide. If, however, symbol belongs to one of the :hide-packaged packages, events of symbol become visible only after the package is :unhide-package 'd. symbol must be a symbol.

:unhide-package package[Break Loop Command]

:unhide-package is the inverse command of :hide-package. However, an event whose event symbol belongs to package becomes visible only after the symbol is :unhide 'd, if the symbol was :hide 'd before. package may be any object that represents a package, i.e., a package object, a symbol, or a string.

Example:

>(defun fact (x) (if (= x 0) one (* x (fact (1- x)))))
fact                   ;;;  Wrong definition for  fact , the factorial. 
	
>(fact 6)              ;;;  Tries to calculate factorial 6. 

Error: The variable ONE is unbound.
Error signalled by IF.

Broken at IF:          ;;;  Enters the break-loop. 
>>:h                   ;;;  Help. 
:c(urrent)             Shows the current function.
:p(revious)            To the previous function.
:n(ext)                To the next function.
:b(acktrace)           Prints backtrace.
:h(elp)                Help.
:q(uit)                Returns to top-level.
:r(esume)              Returns to the caller of break-level.
:l(ocal)               Shows the n-th local value on the stack.
:v(ariables)           Shows local variables.
:functions             Shows local functions.
:blocks                Shows block names.
:tags                  Shows tags.
:(un)hide(-package)    (Un)hide a function (or a package).

>>:b                   ;;;  Backtrace. 
Backtrace: eval > fact > if > fact > if > fact > if > fact >
if > fact > if > fact > if > fact > IF

>>:p                   ;;;  Moves to the previous event. 
Broken at FACT.

>>:b                   ;;;  Now inside of  fact  but outside of  if . 
Backtrace: eval > fact > if > fact > if > fact > if > fact > 
if > fact > if > fact > if > FACT > if

>>:v                   ;;;  Shows local variables. 
Local variables: x.

>>x                    ;;;  The value of  x  is  0 . 
0

>>:blocks              ;;;  Shows blocks. 
Block names: fact.

>>(return-from fact 1) ;;;  Returns from the  fact  block with value  1 . 
720                    ;;;  Now the correct answer. 

>                      ;;;  Top-level.